{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# hvPlot.labels\n",
    "\n",
    "```{eval-rst}\n",
    ".. currentmodule:: hvplot\n",
    "\n",
    ".. automethod:: hvPlot.labels\n",
    "```\n",
    "\n",
    "## Backend-specific styling options\n",
    "\n",
    "```{eval-rst}\n",
    ".. backend-styling-options:: labels\n",
    "```\n",
    "\n",
    "## Examples\n",
    "\n",
    "### Basic points plot with labels\n",
    "\n",
    "This example shows how to overlay textual labels (e.g., a city name) on a 2D scatter plot. In order to avoid the labels being overlaid with the markers, the styling option `text_baseline` is set to `'bottom'`, declaring that each label should be displayed above the point location."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas\n",
    "import pandas as pd\n",
    "\n",
    "df = pd.DataFrame({\n",
    "    'city': ['Buenos Aires', 'Brasilia', 'Santiago', 'Bogota', 'Caracas'],\n",
    "    'country': ['Argentina', 'Brazil', 'Chile', 'Colombia', 'Venezuela'],\n",
    "    'lat': [-34.58, -15.78, -33.45, 4.60, 10.48],\n",
    "    'lon': [-58.66, -47.91, -70.66, -74.08, -66.86],\n",
    "})\n",
    "\n",
    "df.hvplot.points(x='lon', y='lat') * \\\n",
    "df.hvplot.labels(x='lon', y='lat', text='city', text_baseline='bottom', hover=False, padding=0.2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Labels defined with a template string"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This example shows how to use a template string for the text parameter to label each earthquake with both its location and magnitude."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas # noqa\n",
    "\n",
    "df = hvplot.sampledata.earthquakes(\"pandas\")\n",
    "\n",
    "# Use only high-magnitude earthquakes to reduce clutter\n",
    "df = df[df.mag > 6]\n",
    "\n",
    "df.hvplot.points(x=\"lon\", y=\"lat\") * \\\n",
    "df.hvplot.labels(\n",
    "    x=\"lon\", y=\"lat\",\n",
    "    text=\"{place}\\nMag: {mag:.1f}\", text_align=\"left\",\n",
    "    text_font_size=\"8pt\", padding=2,\n",
    ")"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
